Dokumentacja do bramek wtyczki SMS

2003-05-16 v1.7 - nowy LuaPlus.dll

Wtyczka Konnekt->SMS wysy│a kr≤tkie wiadomo╢ci tekstowe przy pomocy skrypt≤w, kt≤re maj▒ do dyspozycji odpowiedni interfejs. DziΩki temu tekstowi dowiesz siΩ co umo┐liwia wtyczka, a przegl▒daj▒c gotowe bramki na pewno nauczysz siΩ pisaµ w│asne skrypty :). SMS mo┐e byµ wykorzystywany do bardzo wielu cel≤w, niekoniecznie zwi▒zanych z SMSami wysy│anymi na kom≤rki. Mo┐na np. przygotowaµ skrypt wrzucaj▒cy tekst na bloga, lub newsa na stronΩ...
Aktualnie jedynym obs│ugiwanym jΩzykiem skryptowym jest jΩzyk LUA.

Ka┐da bramka sk│ada siΩ z 3 czΩ╢ci: definicji w jΩzyku XML, skryptu w jΩzyku LUA i plik≤w dodatkowych jak logo (.ico). Poni┐ej znajdziesz opis wszystkich kolejnych czΩ╢ci...

Definicja w XML

Podczas uruchamiania programu w katalogu konnekt/sms wczytywane s▒ wszystkie pliki XML. Na ich podstawie przygotowywane s▒ bramki. Poni┐ej znajduje siΩ przyk│adowy XML razem z komentarzami, elementy pogrubione s▒ wymagane.

Format pliku musi byµ poprawny. Wbudowany parser nie posiada kontroli b│Ωd≤w i generalnie ma wyj▒tkowo uproszczon▒ konstrukcjΩ. Wszystkie atrybuty musz▒ byµ zawarte w cudzys│owach. Aktualnie rozpoznawane s▒ tylko &qt; w atrybutach i &lt i > w tek╢cie.
Jedyne dozwolone kodowanie to Windows-1250

<?xml version="1.0" encoding="Windows-1250"?>
<sms>

<id>ABC</id>:
<name>Przyk│ad</name>:
<logo>ico.ico</logo>:
<author>...</author>:
<version>luty 2003</version>:
<info>Ble ble ble</info>:
<authorURL>http://.../</authorURL>:
<gateURL>http://.../</gateURL>:
<acceptNumber>(\+48)?0?[56]\d{8}</acceptNumber>:
<scriptFile>pf.lua</scriptFile>:
<maxChars>469</maxChars>:
<maxSendCount>20</maxSendCount>:
<maxParts>1</maxParts>:
<maxCharsOnServer>150</maxCharsOnServer>:
<signature disabled="1">Podpis</signature>:
<params>:
</params>

</sms>

skrypt (LUA)

Aby wys│aµ wiadomo╢µ, SMS kompiluje skrypt i uruchamia go za ka┐dym razem od nowa! Jednym s│owem stan skryptu i jego zmiennych nie bΩdzie pamiΩtany pomiΩdzy wywo│aniami. Je┐eli musisz co╢ zapamiΩtaµ pomiΩdzy sesjami do wykorzystania s▒ funkcje getVar i setVar...
Skrypty mog▒ byµ r≤wnie┐ w skompilowanej formie (*.luac). Jedyny kompilator z jakim wsp≤│pracuje sms.dll jest ten dostarczony razem z LuaPlus. Skrypt musi posiadaµ jedn▒ funkcjΩ - sendSMS do kt≤rej, jako jedyny parametr przekazywana jest tablica asocjacyjna z tymi kluczami/warto╢ciami:

msg: Tre╢µ wiadomo╢ci. Je┐eli wiadomo╢µ by│a d│u┐sza ni┐ maxChars ka┐da z czΩ╢ci wysy│ana jest osobno, a na pocz▒tku wiadomo╢ci do│▒czony jest jej numer.
to: Numer docelowy (mo┐e byµ dowolnym ci▒giem znak≤w).
from: Sygnaturka / Podpis
...: Pozosta│e elementy listy to parametry zdefiniowane w XMLu.

Zwr≤cona warto╢µ nie jest brana pod uwagΩ.

Katalogiem aktywnym skrypt≤w jest katalog Konnekta.
Je┐eli bramka ma korzystaµ z rozszerzonych funkcji internetowych, mo┐e okazaµ siΩ przydatny skrypt "const.lua" ze sta│ymi do przekazywania do funkcji...

SMS.dll jest obecnie skompilowany z bibliotek▒ LuaState chodz▒c▒ na LUA w wersji 4.2.1.

Funkcje

Du┐a czΩ╢µ atrybut≤w jest my╢lΩ na tyle jasna, ┐e pozwoli│em sobie ich nie opisywaµ.
Je┐eli funkcja zwraca wiΩcej ni┐ jedn▒ warto╢µ, s▒ one podane w kolejno╢ci zwracania.
Je┐eli funkcja zwraca bool, to oznacza on, czy operacja siΩ uda│a, czy nie...

Podstawowe

setInfo(info [, typ])

Dodaje now▒ informacjΩ do okienka ze stanem przesy│anych wiadomo╢ci.
info - tekst
typ - typ (INFO_ w const.lua)

setError([komunikat])

Ustawia komunikat b│Ωdu. Ca│a operacja bΩdzie uznana za nieudan▒.

setSuccess([komunikat])

Ustawia komunikat "sukcesu". Ca│a operacja bΩdzie uznana za udan▒ (domy╢lnie jest).

bool setParam(nazwa , warto╢µ)

Ustawia warto╢µ parametru (zdefiniowanego w XMLu).

bool setVar(nazwa , warto╢µ)

Ustawia zmienn▒ bramki. Zmienne przechowywane s▒ przez ca│y czas dzia│ania programu, i mo┐na je odczytywaµ przy pomocy getVar. Aby usun▒µ zmienn▒, trzeba wywo│aµ setVar tylko z pierwszym parametrem.

Od wersji 1.7 mo┐na czytaµ/ustawiaµ zmienne obs│uguj▒ce bramkΩ jak:

author
info
sigInfo
sigEnabled
maxChars
maxSendCount
maxParts
maxCharsOnServer
usageCount
sentCount

warto╢µ getVar(nazwa)

Pobiera warto╢µ zmiennej bramki.

refreshStatus()

Od╢wie┐a zawarto╢µ statusu okienka (ilo╢µ wprowadzonych znak≤w itp.).

LOG(tekst)

Zapisuje do konnekt.log informacjΩ tekstow▒. Do│▒czane s▒ do niej fragment przesy│anej wiadomo╢ci i nazwa bramki.

include(nazwa_pliku)

Wykonuje plik tak samo jak dofile, z t▒ r≤┐nic▒, ┐e ╢cie┐ka jest relatywna do ╢cie┐ki aktualnie wykonywanego skryptu.

czas time()

Zwraca aktualny czas w sekundach, tak samo jak f-cja time w C.

tekst_w_iso cp2iso(tekst_w_cp)

Zmienia kodowanie Windows-1250 na Iso-8859-2

tekst_w_cp iso2cp(tekst_w_iso)

Zamienia kodowanie znak≤w Iso-8859-2 na Windows-1250

tekst_bez_polskich hidePL(tekst)

Usuwa ogonki, w tek╢cie kodowanym w standardach zar≤wno CP jak i ISO.

nowy_tekst urlEncode(tekst)

Zamienia wszystkie znaki nie alfa-numeryczne na %warto╢µ_znaku_w_hexie

nowy_tekst urlDecode(tekst)

Odwraca proces wykonany przez urlEncode :)

Okna dialogowe

alert(tekst [ , tytu│]): Wy╢wietla standardowe okienko dialogowe.
bool confirm(zapytanie [ , tytu│]): Wy╢wietla standardowe zapytanie TAK/NIE i zwraca true/false.
token getToken(info , obraz): Wy╢wietla informacjΩ, obrazek, pole do wpisywania tekstu i zwraca wpisan▒ warto╢µ. Os│awionym przyk│adem s▒ tokeny Ideii.
info - informacja wy╢wietlana nad obrazkiem.
obraz - ╢cie┐ka do pliku z obrazkiem do wy╢wietlenia.

token - wpisany tekst.

Wyra┐enia regularne

Je┐eli nie znasz Regular Expressions, poczytaj ich opis na stronie www.php.net
Wszystkie wzorce musz▒ byµ "zamkniΩte" w dwa takie same znaki nie alfa-numeryczne. np.:
"/[abc]+/" , lub "#[abc]#"
Drugi przyk│ad jest wygodne o tyle, ┐e nie wymaga escape'owania znaku '/'. Na ko±cu, za znakiem zamkniΩcia wzorca mo┐na podawaµ standardowe flagi jak:
i , m, s , x ,
jak r≤wnie┐ flagi rozszerzone jak:
A - wzorzec przyr≤wnywany jest do ca│ego tekstu , D - znak $ oznacza tylko koniec tekstu , 8 - tekst jest w formacie UTF8.
Trzeba pamiΩtaµ, ┐e przekazywane │a±cuchy znak≤w s▒ escape'owane znakiem '\'. Wszystkie '\' kt≤re musz▒ znale╢µ siΩ we wzorcu musz▒ byµ wpisane dwukrotnie. Aby tego unikn▒µ, mo┐na tekst przekazywaµ jako [[....]].

wynik preg_match(wzorzec , tekst [ , trafienia]): Wykonuje przyr≤wnanie do wzorca.
tekst - tekst do przyr≤wnania
trafienia - tablica do kt≤rej zostan▒ zapisane wyniki. Na pozycji 0 zostanie zapisany ca│y pasuj▒cy fragment tekstu, a na kolejnych fragmenty pasuj▒ce do poszczeg≤lnych podwzorc≤w.
wynik - 0 , lub 1 + liczba pasuj▒cych podwzorc≤w.
wynik preg_matchAll(wzorzec , tekst [ , trafienia]): Wykonuje przyr≤wnanie do wzorca. Wzorzec nak│adany jest wielokrotnie na ca│y tekst.
warto╢ci preg_matchReturn(wzorzec , tekst): Po przyr≤wnaniu pasuj▒cy fragment tekstu zwracany jest jako pierwszy, a nastΩpnie wszystkie pasuj▒ce podzworce. Np:
data , rok , miesiac , dzien = preg_matchReturn('/(\\d{4})-(\\d{1,2})-(\\d{1,2})'/ , 'Dzi╢ jest 2003-02-20');
nowy_tekst preg_replace(wzorzec , zamiana , tekst [ , limit=0]): Podmienia tekst wed│ug podanego wzorca.
zamiana - tekst, kt≤rym bΩd▒ podmieniane pasuj▒ce do wzorca fragmenty tekstu. Mo┐na wykorzystywaµ znalezione podwzorce, s│u┐▒ do tego znaki $ (jak w Perlu) i \ (jak w PHP).
Po $ lub \ trzeba podaµ numer podwzorca od 0 do 9, gdzie 0 jest ca│ym pasuj▒cym fragmentem.
Podobnie jak w Perlu $& jest r≤wnoznaczne $0.
limit - limit │▒cznej ilo╢ci wykonywanych podmian. 0 - bez limitu

Obs│uga sieci

Funkcje obs│ugi sieci bazuj▒ w pe│ni na f-cjach sieciowych windowsowej biblioteki WinInet, tej samej, z kt≤rej korzysta Internet Explorer. Na MSDN mo┐na znale╝µ ich pe│n▒ dokumentacjΩ... Funkcje maj▒ te same nazwy, i zbli┐one atrybuty (kolejno╢µ na og≤│ jest identyczna, nie ma za to atrybut≤w zbΩdnych i w niekt≤rych przypadkach tych, kt≤rych obs│ugi po prostu tutaj nie ma...). W miarΩ mo┐liwo╢ci zachowa│em tutaj podobne nazwy atrybut≤w.
Wszystkie utworzone uchwyty powinno siΩ zamykaµ, ale nie trzeba, SMS jest wyposa┐ony w kolektor ╢mieci i po zako±czeniu wykonywania skryptu sam je zwolni.

HSession InternetOpen([UserAgent]): Tworzy sesjΩ. Pierwsza rzecz do wywo│ania.
HConnection InternetConnect(HSession , ServerHost [ , ServerPort=80 , UserName , Password ]): Nawi▒zuje po│▒czenie z podanym serwerem (IP lub domena).
HRequest HttpOpenRequest(HConnection[ , Method=GET , Action=/ , Referrer , Flags]): Tworzy zapytanie (jeszcze go nie wysy│a!). Wersja ustawiona jest na sztywno na HTTP/1.0
Method - GET / POST
Action - plik/katalog o kt≤ry chcemy siΩ "pytaµ". Np "/open.php?module=forum".
Flags - INTERNET_FLAG_* z const.lua
bool HttpSendRequest(HRequest [ , Header , Data ]): Wysy│a zapytanie
Header - dodatkowe nag│≤wki do do│▒czenia
Data - dodatkowe dane do do│▒czenia po nag│≤wkach. W tym atrybucie przekazujemy to co chcemy POSTowaµ.
Data InternetReadFile(HRequest): Pobiera wynik wys│anego zapytania.
bool InternetWriteFile(HRequest , data): W tej chwili nie widzΩ jeszcze zastosowania w skryptach... Ale na pewno przyda siΩ kiedy╢ przy obs│udze FTP.
InternetCloseHandle(HINTERNET): Zamyka dowolny otwarty uchwyt sieciowy (H*)
Cookie InternetGetCookie(URL): Pobiera Cookie dla podanego URL'a
bool InternetSetCookie(URL , Name , CookieData): Ustawia Cookie dla podanego URLa
ErrorNo , ErrorMsg InternetGetLastResponseInfo(): Pobiera kod b│Ωdu ostatniej operacji. Przy HTTP najczΩ╢ciej niewiele zwr≤ci...
Info HttpQueryInfo(HRequest , InfoLevel): Pobiera informacjΩ o zapytaniu. Przydaje siΩ do analizowania nag│≤wk≤w odpowiedzi serwera, zw│aszcza HTTP_QUERY_STATUS_CODE i HTTP_QUERY_STATUS_TEXT
InfoLevel - HTTP_QUERY_* w const.lua
bool InternetSetOption(HINTERNET , Flag , Data): Ustawia opcjΩ kt≤rego╢ z uchwyt≤w.
Flag - INTERNET_OPTION_ w const.lua
Data InternetQueryOption(HINTERNET , Flag): Pobiera opcjΩ kt≤rego╢ z uchwyt≤w.
Flag - INTERNET_OPTION_ w const.lua

Zmiany

v1.7

Przy pomocy getVar i setVar mo┐na zmieniaµ/odczytywaµ zmienne bramki, kt≤re pod tymi samymi nazwami zosta│y wczytane z XML'a
W wersji 5.0.0.1 LuaPlus.dll w tablicy math dostΩpne s▒ funkcje:
and , or , not , xor , imod , lshift , rshift , arshift
s│u┐▒ce do operacji binarnych na liczbach.

v1.6

Enginem LUA jest teraz LuaPlus, oparte na LUA w wersji 5.0 (beta).
Przypominam ┐e w LuaPlus wszystkie funkcje bibliotek LUA pogrupowane s▒ w obiekty jak math, string itd.!
Dodatkowo dzia│aj▒ metatables czyli np: foo = "bar" alert(foo:len())
Uchwyty do f-cji internetowych zbierane s▒ kolektorem ╢mieci, wiΩc o ile zamykanie tych uchwyt≤w jest dobr▒ praktyk▒, to wcale nie jest wymagane.
ProszΩ jednak pamiΩtaµ, ┐e uchwyty do plik≤w MUSZí byµ zamykane!
Engine i wszystkie funkcje og≤lne zosta│y wydzielone do osobnego DLLa. W ten spos≤b mo┐e z nich korzystaµ r≤wnie┐ kBot.
Poprawione dzia│anie funckji include
Jest mo┐liwo╢µ dumpowania obiekt≤w, zar≤wno do pliku (standardowe zachowanie LuaPlus) jak i do zmiennej tekstowej:
zrzut = LuaDumpObject(nil , 'nazwa' , zmienna)
Za pierwszy parametr mo┐na podstawiµ nazwΩ pliku, do kt≤rego zostanie zapisany wynik.

v1.4

Rozszerzenie zestawu funkcji
W tablicy przekazywanej do sendSMS nie ma ju┐ element≤w: toNr , fromNr , fromName i fromEmail. Zast▒pione zosta│y polami to i from. Dla zachowania zgodno╢ci stare pola pozostan▒ do nastΩpnej wersji, przy czym toNr=to , fromName=from , fromNr=fromEmail="".